SK-3253:Add gated retry on 401 status code for flowvault SDK - #454

SK-3253: Retry once on 401 when the bearer token expired mid-call

Ticket: SK-3253 (customer case CUST-4591)

Problem

Every vault method checks the bearer token once, at its start, with now > exp. The token is then used for every HTTP request that method sends. If it expires while a request is in flight, or between the check and a later request of the same method, the gateway answers 401 and the SDK returns that as the result. Nothing regenerates the token until the next method call.

In flowvault a bulk method splits records into batches and sends each batch as its own request under that one check. A customer's bulk tokenize of 2,000 records started a few seconds before expiry, passed the check, and lost every batch after exp as per-record httpCode=401 errors.

Fix

When a request fails with 401 and the SDK can see from its own copy of the token that the token is at or past expiry, the SDK generates a new token once and resends that request once.

• Trigger is 401 only. Any other status is returned as today.
• Only for credentials the SDK can mint from: service-account file, credentials string, environment credentials. A static token (setToken) or an API key returns the 401 unchanged.
• Only when the sent token's exp is within 60 seconds of now. A 401 on a token with more life than that is not expiry and is returned unchanged, with no token generated.
• One regeneration and one resend per request. The response to the resend is returned whatever it is.
• Single-flight. Regeneration is serialised with the existing token check. A request that finds the cache already holds a different token reuses it, so concurrent 401s on one token cost one generation.
• If generation fails, or returns the token that was just rejected, the original 401 is returned.

Later requests in the same method read the refreshed token from the cache, so a bulk call that crosses expiry now completes in full. No new configuration. The start-of-method check is unchanged.

Changes

common

• BaseVaultClient: the auth interceptor used by every OkHttp client now handles the 401 branch. New refreshBearerTokenAfterUnauthorized implements the rules above, synchronized with setBearerToken. Token reads go through a synchronized getToken() so a token refreshed on one thread is seen by the others.
• Token.isExpiringWithin(token, windowSeconds): public, additive. isExpired is unchanged.
• New InfoLogs / WarningLogs entries for the refresh path. No new logging on the happy path.

flowvault

• VaultClient: uses the shared auth interceptor from common. The transport retry interceptor stays outside it, so configured 408/429/5xx retries and the call timeout still bound the whole exchange.

skyvault

• VaultClient: token supplier switched to getToken(). Vault and detect calls get the retry through the shared interceptor.
• Connections are intentionally unchanged. A connection 401 can come from the proxied third party, and a resend there is not guaranteed to be side-effect free.

Not covered, by design

setToken tokens, API keys, any 401 on a token that is not near expiry, a connection call that straddles expiry. All behave exactly as today.

Tests

• common: BaseVaultClientTests (interceptor branches, gate, single-flight, same-token-back, failure), TokenTests (isExpiringWithin boundaries, malformed and missing exp).
• flowvault: AuthInterceptorTests (retry ordering, resend once, static token and API key untouched).
• All three module suites pass. flowvault japicmp against the baseline passes; the only public API change is the new Token.isExpiringWithin.